home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Devices and Hardware / Drivers / TradDriverLoaderLib / TradDriverLoaderLib.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-28  |  10.2 KB  |  220 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        TradDriverLoaderLib.h
  3.     
  4.     Description:C interface for the pseudo-DriverLoaderLib for 'DRVR's.
  5.  
  6.     Author:        Quinn "The Eskimo!"
  7.  
  8.     Copyright:     Copyright: © 1996-1999 by Apple Computer, Inc.
  9.                 all rights reserved.
  10.     
  11.     Disclaimer:    You may incorporate this sample code into your applications without
  12.                 restriction, though the sample code has been provided "AS IS" and the
  13.                 responsibility for its operation is 100% yours.  However, what you are
  14.                 not permitted to do is to redistribute the source as "DSC Sample Code"
  15.                 after having made changes. If you're going to re-distribute the source,
  16.                 we require that you make it clear in the source that the code was
  17.                 descended from Apple Sample Code, but that you've made changes.
  18.     
  19.     Change History (most recent first):
  20.                 6/23/99    Updated for Metrowerks Codewarrior Pro 2.1(KG)
  21.  
  22. */
  23.  
  24. #include <Types.h>
  25. #include <Devices.h>
  26.  
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31. ///////////////////////////////////////////////////////////////////////////
  32.  
  33. // The following routines are implemented with semantics virtually identical
  34. //  to those found in DriverLoaderLib.  You should look in
  35. //  "Designing PCI Cards and Drivers for Power Macintosh Computers" for
  36. //  documentation.  You can FTP an electronic copy from:
  37. /*  <ftp://ftpdev.info.apple.com//Developer_Services/
  38.      Technical_Documentation/PCI_Information/Designing_PCI_Cards_-_Driv.sit.>
  39. */
  40.  
  41. extern pascal SInt16 TradHigherDriverVersion(NumVersion *dv1, NumVersion *dv2);
  42.  
  43. extern pascal UnitNumber TradHighestUnitNumber(void);
  44.  
  45. extern pascal OSErr TradDriverGestaltOn(DriverRefNum refNum);
  46.  
  47. extern pascal OSErr TradDriverGestaltOff(DriverRefNum refNum);
  48.  
  49. extern pascal Boolean TradDriverGestaltIsOn(DriverFlags flags);
  50.  
  51. extern pascal OSErr TradLookupDrivers(UnitNumber beginningUnit,
  52.                                         UnitNumber endingUnit,
  53.                                         Boolean emptyUnits,
  54.                                         ItemCount *returnedRefNums, 
  55.                                         DriverRefNum *refNums);
  56.  
  57. ///////////////////////////////////////////////////////////////////////////
  58.  
  59. // The following routines are similar to the corresponding routines in
  60. //  DriverLoaderLib, but their interface differs because of the
  61. //  inherent differences between 'DRVR's and 'ndrv's.  The comments
  62. //  cover the differences for each routine.  If there's a difference
  63. //  that's not commented, it's most probably a bug and you should let
  64. //  me know.
  65.  
  66. extern pascal OSErr TradInstallDriverFromPtr(DRVRHeaderPtr driver,
  67.                                                 UnitNumber beginningUnit,
  68.                                                 UnitNumber endingUnit,
  69.                                                 DriverRefNum *refNum);
  70.     // This routine is similar to InstallDriverFromMemory except
  71.     //  that you pass a pointer to the 'DRVR', rather than a base pointer
  72.     //  and length.  This pointer is copied verbatim into the dCtlDriver
  73.     //  field of the DCE, so you have to make sure that it's in
  74.     //  the system heap if the driver is going to hang around longer than
  75.     //  your application.
  76.     // One other deviation from InstallDriverFromMemory is that this
  77.     //  call won't replace an existing driver.  This is because 'DRVR's
  78.     //  don't have infrastructure to support this.  If there's already
  79.     //  a driver of the same name in the unit table, the call will fail
  80.     //  with a dupFNErr, and *refNum will be set to the refnum of the
  81.     //  existing driver.
  82.     // The semantics of the endingUnit match those of DriverLoaderLib,
  83.     //  ie the call will not grow the unit table unless endingUnit is
  84.     //  greater than TradHighestUnitNumber.  The simplest way to work
  85.     //  this is to pass TradHighestUnitNumber() + 1 to endingUnit.
  86.     // If the call fails, it's your responsibility to dispose of the
  87.     //  the driver pointer.  If it succeeds, the system has a copy
  88.     //  of the pointer, which can be disposed by calling TradRemoveDriver.
  89.  
  90. extern pascal OSErr TradInstallDriverFromHandle(DRVRHeaderHandle driver,
  91.                                                 UnitNumber beginningUnit,
  92.                                                 UnitNumber endingUnit,
  93.                                                 DriverRefNum *refNum);
  94.     // This routine is similar to InstallDriverFromMemory except
  95.     //  that you pass a handle to the 'DRVR', rather than a base pointer
  96.     //  and length.  This is generally more convenient in the traditional
  97.     //  'DRVR' world.
  98.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  99.     //  The routine simply creates a pointer in the system heap and copies
  100.     //  your driver into it, then calls TradInstallDriverFromPtr.  Because
  101.     //  a copy is made, you do not have to ensure that the handle you
  102.     //  pass in is in the system heap.
  103.     // Regardless of whether call succeeds or fails, it's your responsibility
  104.     //  to dispose of the driver handle.
  105.     
  106. extern pascal OSErr TradInstallDriverFromResource(SInt16 rsrcID, StringPtr rsrcName,
  107.                                                 UnitNumber beginningUnit,
  108.                                                 UnitNumber endingUnit,
  109.                                                 DriverRefNum *refNum);
  110.     // This call offers functionality like InstallDriverFromFile.
  111.     //  It differs from InstallDriverFromFile in that the driver is expected
  112.     //  to be in a resource in the current resource file.  If rsrcName is nil,
  113.     //  the call uses Get1Resource('DRVR', rsrcID) to get the driver.  If
  114.     //  rsrcName is not nil, it uses Get1NamedResource('DRVR', rsrcName)
  115.     //  to get the driver.
  116.     // In most other respects, this routine works like TradInstallDriverFromPtr.
  117.     // If the call fails, the routine will clean up after itself.  If the
  118.     //  call succeeds, the driver code is left as a memory block in the system
  119.     //  heap, which can be cleaned up by calling TradRemoveDriver.
  120.  
  121. extern pascal OSErr TradGetDriverInformation(DriverRefNum refNum,
  122.                                                 UnitNumber *thisUnit,
  123.                                                 DriverFlags *flags,
  124.                                                 StringPtr name,
  125.                                                 DRVRHeaderPtr *driverHeader
  126.                                                 );
  127.     // This routine is like GetDriverInformation except that it only
  128.     //  returns information that's pertinant to the traditional 'DRVR'
  129.     //  world.  driverHeader comes back as a pointer to the beginning
  130.     //  of the 'DRVR' header.
  131.     // Note that this routine works for both drivers installed by
  132.     //  this library and other drivers, however for drivers not installed
  133.     //  by this library (ie 'RAM'-based drivers), driverHeader may be a 
  134.     //  half dereferenced handle, locked or unlocked.  You have been warned.
  135.     // Also, driverHeader can come back set to nil, if the driver
  136.     //  is installed but its code has been purged, for example a DA.
  137.     //  You must check for this before deferencing it.  If driverHeader
  138.     //  is set to nil, name will be set to the empty string.
  139.  
  140. extern pascal OSErr TradOpenInstalledDriver(DriverRefNum refNum, SInt8 ioPermission);
  141.     // This routine has the same semantics as OpenInstalledDriver
  142.     //  except that the ioPermission parameter must be fsRdWrPerm.  This is
  143.     //  because we call through to the Device Manager's OpenDriver routine,
  144.     //  and that doesn't support passing in permissions.  I could switch the
  145.     //  implementation to use PBOpen, but PBOpen is a trap fraught with much
  146.     //  danger, so I'm avoiding it at the moment.
  147.     // The danger associated with PBOpen is that it's highly overloaded,
  148.     //  being used for FSOpen, PBOpen, PBHOpen, OpenSlot, OpenDriver,
  149.     //  OpenDeskAcc, and so on.  If you get the glue wrong, you die in
  150.     //  strange and evil ways.  So I'm bypassing the entire problem by
  151.     //  ignoring ioPermission.  I may revisit this decision, but not soon.
  152.  
  153. extern pascal OSErr TradRemoveDriver(DriverRefNum refNum, Boolean immediate);
  154.     // This routine implements similar semantics to RemoveDriver, except
  155.     //  that the Immediate parameter must be false.  This is because
  156.     //  we close the driver using PBCloseSync, which is a queued
  157.     //  command, just like all the others.  We have no way to bypass
  158.     //  this.
  159.     // An important thing to note is that you should only call this on drivers
  160.     //  you installed using this library's TradInstallDriverFromHandle
  161.     //  and TradInstallDriverFromResource routine.  Don't call it on
  162.     //  drivers installed by other people and be careful when calling it on
  163.     //  drivers installed using TradInstallDriverFromPtr because you might
  164.     //  be disposing the driver code even though a) it might not actually be a
  165.     //  Memory Manager pointer block, or b) it might be still in use
  166.     //  by another driver.
  167.  
  168. extern pascal OSErr TradRenameDriver(DriverRefNum refNum, ConstStr255Param newDriverName);
  169.     // This routine is implemented with the caveat that you can't
  170.     //  make the driver name longer.  This is because the 'DRVR'
  171.     //  name is actually stored in the code resource which implements
  172.     //  the driver, and making it longer would cause it to run into
  173.     //  the code that immediately follows the name.
  174.     // The reason why I implemented this routine at all is because
  175.     //  it's useful for installing multiple copies of the same driver.
  176.     //  For example, you can install ".Q_Out", then rename it to
  177.     //  ".QAOut", and then install ".Q_Out" again, and rename that to
  178.     //  ".QBOut".  This can be very useful when testing and debugging
  179.     //  your driver (or TradDriverLoaderLib for that matter :).
  180.     // You should take extreme care when calling this routine on drivers that
  181.     //  weren't installed with this library.  Some of these drivers might
  182.     //  not like being renamed in this way.
  183.  
  184. ///////////////////////////////////////////////////////////////////////////
  185.  
  186. // The following routines from DriverLoaderLib were not implemented because
  187. //  they make no sense at all in the world of 'DRVR's.
  188.  
  189. // VerifyFragmentAsDriver
  190. // GetDriverMemoryFragment
  191. // GetDriverDiskFragment
  192. // InstallDriverFromFragment
  193. // SetDriverClosureMemory
  194. // -- If they've got fragment in the name, it's hard to map them into the
  195. // 'DRVR' world.  Traditional 'DRVR's just aren't code fragments!
  196.  
  197. // InstallDriverFromFile -- This routine assumes that there's only
  198. //    one driver in a file, which is not the case for traditional 'DRVR's
  199. //  which are normally stored as resources.  The basic functionality has
  200. //  been subsumed by TradInstallDriverFromResource.
  201.  
  202. // InstallDriverFromDisk
  203. // FindDriversForDevice
  204. // FindDriverCandidates
  205. // ScanDriverCandidates
  206. // GetDriverForDevice
  207. // InstallDriverForDevice
  208. // -- These routines all assume that there's some magic way of matching
  209. //  drivers to their name register nodes.  In the traditional world, there
  210. //  is no name registry and, even if there was, there's no way to match
  211. //  devices against hardware.  So these routines are not sensible in the
  212. //  traditional world. 
  213.  
  214. // ReplaceDriverWithFragment -- There's no good way to replace a traditional
  215. //  device driver; the infrastructure just isn't there.
  216.  
  217. #ifdef __cplusplus
  218. }
  219. #endif
  220.